home *** CD-ROM | disk | FTP | other *** search
/ Info-Mac 4 / Info_Mac IV CD-ROM (Pacific HiTech Inc.)(August 1994).iso / Science / RLaB / help / FUNCTION < prev    next >
Text File  |  1994-04-25  |  7KB  |  234 lines
  1. FUNCTION:
  2.  
  3.     Functions are an essential part of the language. Functions
  4.     arguments are passed by REFERENCE (ala FORTRAN). Functions
  5.     return a single value (if you must return multiple objects
  6.     group them together in a LIST). By default all function
  7.     variables are GLOBAL, unless declared local.
  8.  
  9.     Functions in RLaB are treated as objects, in a manner similar
  10.     to matrices (see below for further explanation). Thus, users
  11.     can assign/copy user-functions like ordinary variables. This
  12.     leads to the slightly unusual syntax used for a function
  13.     declarations.
  14.  
  15.     Example:
  16.  
  17.     > sum = function (s) 
  18.       {
  19.         local(i, Sum);
  20.         Sum = 0;
  21.         for(i in 1:size(s)) {
  22.           Sum = Sum + s[i];
  23.         }
  24.         return Sum;
  25.       };
  26.     >
  27.  
  28.     creates a function, and assigns it to the variable `sum'.
  29.     Sum is invoked like:
  30.  
  31.     > sum( [1,2,3,4,5] )
  32.         15
  33.     ----------------------------------------------------------------
  34.  
  35.     Functions can return a single entity to the calling
  36.     environment. If it is necessary to return more than one
  37.     entity, a list can be used to group multiple entities together
  38.     for return.
  39.  
  40.     Example:
  41.  
  42.     We want to write a function that creates a set of matrices (a
  43.     state-space model). We will write such a function, and group
  44.     the separate matrices together in a list.
  45.  
  46.     > ss = function( w )
  47.       {
  48.          local(A, B, n);
  49.         n = size( w )[1];
  50.         A = [ zeros(n,n), eye(n,n);
  51.               -w;         zeros(n,n) ];
  52.         B = ones(n,n);
  53.      
  54.          return << A = A; B = B >>;
  55.       };
  56.     >
  57.  
  58.     The return statement creates the list, and assign the names
  59.     `A' and `B' to it's members.    
  60.  
  61.     Functions always return something, even though the return
  62.     statement is optional. 
  63.  
  64.     ----------------------------------------------------------------
  65.  
  66.     Functions can call themselves recursively. Since a function is
  67.     stored in the same manner as a variable, the function can be
  68.     deleted, or renamed. Therefore, users must be careful not to
  69.     rename functions that call themselves, or they must use the
  70.     `$self' keyword.
  71.  
  72.     Example:
  73.  
  74.     > fact = function (f) 
  75.       {
  76.         if(f <= 1) {
  77.           return 1;
  78.         else
  79.           return f*$self(f-1);
  80.         }
  81.       };
  82.     > fact(10)
  83.         3628800
  84.  
  85.     ----------------------------------------------------------------
  86.  
  87.     All function variables are GLOBAL by default. Since builtin
  88.     and user-functions are treated like ordinary variables this
  89.     ensures that user-functions have full access to existing
  90.     functions. If you need local variables, use the local
  91.     statement at the beginning of your function.
  92.  
  93.     Example:
  94.  
  95.     > x = function(y)
  96.      {
  97.        local(i);
  98.        for( i in 1:y.n ) {
  99.          y[i] = 0;
  100.        }
  101.        return y;
  102.      };
  103.     >
  104.  
  105.     The local statement declares `i' to be a local scalar variable
  106.     with initial value UNDEFINED. When the function returns the
  107.     variable `i' will cease to exist. When x() is called again `i'
  108.     will again be re-initialized UNDEFINED. The local statement
  109.     must be the 1st statement in a function, and only one local
  110.     statement is allowed. If you must declare alot of local
  111.     variables, then break the local statement with a continuation.
  112.  
  113.     local(i, j, k,...
  114.            l, m, n);
  115.  
  116.     Local variables are resolved 1st. When a name collision occurs
  117.     between a local variable, and a global variable, including
  118.     builtin functions, the local variable takes precedence.
  119.  
  120.     ----------------------------------------------------------------
  121.  
  122.     You do not have to call a function with the same number of
  123.     arguments specified in the definition. If you invoke a
  124.     function with more arguments than declared, the result is an
  125.     error. If you call the function with less arguments than
  126.     declared, RLaB will pad the argument list with Undefined,
  127.     objects. Additionally, commas may be used to "skip" arguments
  128.     that are unecessary. for each argument that is "skipped" an
  129.     UNDEFINED variable is passed to the function during execution.
  130.  
  131.     Undefined arguments can be detected with the exist function,
  132.     for example: 
  133.  
  134.           if (!exist (ARG))
  135.           {
  136.             ARG = 0;    // Initialize undefined argument
  137.           }
  138.     
  139.     ----------------------------------------------------------------
  140.  
  141.     Lists can be used to get the effect of variable argument
  142.     lists. If you are not familiar with lists, then now would be a
  143.     good time to `help LIST'. A function can take a list as an
  144.     argument and then pull the actual number of list elements, and
  145.     their values, from the list when the function is called. For
  146.     example:
  147.  
  148.     > vlistf = function( l )
  149.       {
  150.         local(i,x);
  151.  
  152.         printf( "number of elements in variable arg-list = %i\n", size(l) );
  153.       
  154.         // Pull each element from the list
  155.       
  156.         for( i in 1:size(l) )
  157.         {
  158.           x = l.[i];
  159.           // now do something with x
  160.         }
  161.       };
  162.     > vlistf( << "string"; [1,2;3,4] >> )
  163.     number of elements in variable arg-list = 2
  164.     
  165.     ----------------------------------------------------------------
  166.  
  167.     Functions can take other functions as arguments, for example:
  168.  
  169.     > trick = function ( a , b )
  170.       {
  171.         a(b)
  172.       };
  173.     > trick( eye, [3,3] );
  174.      matrix columns 1 thru 3
  175.                1           0           0
  176.                0           1           0
  177.                0           0           1
  178.  
  179.     Note that the function name, passed as an argument, did not
  180.     need quotes. This is so because functions are variables in the
  181.     same sense as scalars, strings, and matrices. The variable a
  182.     in the previous function example refers to the function eye,
  183.     since function args are passed by reference.
  184.  
  185.  
  186.     Function references are resolved at run-time. This allows
  187.     users to create or load functions, which refer to other
  188.     functions, without be concerned about the order of definition.
  189.  
  190.     ----------------------------------------------------------------
  191.  
  192.     Notes:
  193.  
  194.     ``Functions in RLaB are treated as objects, in a manner
  195.     similar to matrices.''
  196.  
  197.     The previous statement was used earlier, and deserves a more
  198.     thorough explanation. Internally, functions are objects just
  199.     like matrices, and lists. The major differences are
  200.     operational and syntactical.
  201.  
  202.     Operationally: functions do not share the same set of
  203.     operations that matrices do. For example, you cannot add two
  204.     functions together. The allowable operation on function
  205.     objects is a copy. Thus `a = b' will copy the function `b' to
  206.     the variable `a'.
  207.  
  208.     Syntactically: functions do not enjoy all the syntactic freedoms
  209.     that other object definitions do. For example:
  210.  
  211.     m = ( [1,2,3] )                    // is legal
  212.  
  213.     f = ( function ( x ) { return 2*x; } )        // not legal
  214.  
  215.     The function definition and assignment statements are special
  216.     statements in RLaB, and are not as flexible as other object
  217.     definitions. Additionally, functions cannot be defined/created
  218.     in a list definition:
  219.  
  220.     l = << f = function ( x ) { return 2*x; } >>    // not legal
  221.  
  222.     If you want to include a function as part of a list, then you
  223.     must first create the list, and then add the function to the
  224.     list members, or create the function first, then use it in the
  225.     list declaration:
  226.  
  227.     > f = function ( x ) { return 2*x; }
  228.     > l = << f >>
  229.        1            
  230.     > l.[1]
  231.     > l.[1](2)
  232.             4
  233.     > clear (f);
  234.